# Статическая документация

Scaladoc умеет генерировать статические сайты, известные 
по [Jekyll](http://jekyllrb.com/) или [Docusaurus](https://docusaurus.io/).
Наличие комбинированного инструмента позволяет обеспечить взаимодействие между статической документацией и API, 
что позволяет им естественным образом сочетаться.

Создать сайт так же просто, как и в Jekyll. 
Корень сайта содержит макет сайта, 
и все файлы, размещенные там, будут либо считаться статическими, либо обрабатываться для расширения шаблона.

Файлы, которые рассматриваются для расширения шаблона, 
должны заканчиваться на `*.{html,md}` и в дальнейшем будут называться "файлами шаблонов" или "шаблонами".

Простой сайт "Hello World" может выглядеть примерно так:

```text
.
└── <site-root>/
    └── _docs/
        ├── index.html
        └── getting-started.html
```

Что даст сайт со следующими файлами в сгенерированной документации:

```text
index.html
getting-started.html
```

Scaladoc может преобразовывать как файлы, 
так и каталоги (чтобы организовать документацию в древовидную структуру). 
По умолчанию каталоги имеют заголовок, основанный на имени файла, и имеют пустое содержимое. 
Можно предоставить индексные страницы для каждого раздела, 
создав `index.html` или `index.md` (но не одновременно) в выделенном каталоге.


### Характеристики

Scaladoc использует [механизм шаблонов Liquid](https://shopify.github.io/liquid/)
и предоставляет несколько настраиваемых фильтров и тегов, характерных для документации Scala.

В Scaladoc все шаблоны могут содержать вступительную часть YAML. 
Передняя часть анализируется и помещается в переменную `page`, доступную в шаблонах через Liquid.

Пример вступительной статьи:

```text
---
title: My custom title
---
```

Scaladoc использует некоторые предопределенные свойства для управления аспектами страницы.

Предустановленные свойства:

- **title** обеспечивает заголовок страницы, который будет использоваться в навигации и метаданных HTML.
- **extraCss** - дополнительные файлы `.css`, которые будут включены в эту страницу. 
Пути должны указываться относительно корня документации. Этот параметр не экспортируется в механизм шаблонов.
- **extraJs** - дополнительные файлы `.js`, которые будут включены в эту страницу. 
Пути должны указываться относительно корня документации. Этот параметр не экспортируется в механизм шаблонов.
- **hasFrame** - если установлено значение `false`, 
страница не будет включать макет по умолчанию (навигацию, breadcrumbs и т.д.), 
а только токен-оболочку HTML для предоставления метаданных и ресурсов (файлы js и css). 
Этот параметр не экспортируется в механизм шаблонов.
- **layout** - предопределенный макет для использования, см. ниже. 
Этот параметр не экспортируется в механизм шаблонов.


### Использование существующих шаблонов и макетов

Чтобы выполнить расширение шаблона, Dottydoc просматривает поле `layout` во вступительной части. 
Вот простой пример системы шаблонов в действии `index.html`:

```text
---
layout: main
---

<h1>Hello world!</h1>
```

С таким простым основным шаблоном, как этот:

```
<html>
    <head>
        <title>Hello, world!</title>
    </head>
    <body>
        {\{ content }}
    </body>
</html>
```

`content` будет заменен на `<h1>Hello world!</h1>` в файле `index.html`.

Макеты должны быть размещены в каталоге `_layouts` в корне сайта:

```text
├── _layouts
│   └── main.html
└── _docs
    ├── getting-started.md
    └── index.html
```


### Ресурсы

Чтобы рендерить ассеты вместе со статическим сайтом, их нужно поместить в директорию `_assets` в корне сайта:

```text
├── _assets
│   └── images
│        └── myimage.png
└── _docs
    └── getting-started.md
```

Чтобы сослаться на ресурс на странице, необходимо создать ссылку относительно каталога `_assets`.

```text
Take a look at the following image: [My image](images/myimage.png)
```


### Боковая панель

По умолчанию Scaladoc отображает структуру каталогов из каталога `_docs` на визуализируемом сайте. 
Существует также возможность переопределить его, предоставив файл `sidebar.yml` в корневом каталоге сайта. 
Конфигурационный файл YAML описывает структуру отображаемого статического сайта и оглавление:

```text
index: index.html
subsection:
    - title: Usage
      index: usage/index.html
      directory: usage
      subsection:
        - title: Dottydoc
          page: usage/dottydoc.html
          hidden: false
        - title: sbt-projects
          page: usage/sbt-projects.html
          hidden: false
```

Корневой элемент должен быть `subsection`. 
Вложенные подразделы приведут к древовидной структуре навигации.

Свойства `subsection`:

- `title` - Необязательная строка - заголовок подраздела по умолчанию. 
Вступительные заголовки имеют более высокий приоритет.
- `index` - Необязательная строка - Путь к индексной странице подраздела. Путь указан относительно каталога _`docs`.
- `directory` - Необязательная строка - Имя каталога, в котором будет находиться подраздел сгенерированного сайта. 
По умолчанию именем каталога является имя подраздела, преобразованное в kebab case.
- `subsection` - Массив `subsection` или `page`.

Либо `index`, либо `subsection` должны быть определены. 
Подраздел, определенный с `index` и без `subsection`, будет содержать страницы и каталоги, 
загружаемые рекурсивно из каталога индексной страницы.

Свойства `page`:

- `title` - Необязательная строка - заголовок страницы по умолчанию. 
Вступительные заголовки имеют более высокий приоритет.
- `page` - Строка - Путь к странице относительно каталога `_docs`.
- `hidden` - Необязательное логическое значение. 
Флаг, указывающий, должна ли страница отображаться на боковой панели навигации. 
По умолчанию установлено значение `false`.

> Все пути в файле конфигурации YAML относятся к `<static-root>/_docs`.


### Иерархия title

Если заголовок указан несколько раз, приоритет будет следующим (от высшего к низшему приоритету):

Страница

1. `title` из `front-matter` файла markdown/html
2. `title` свойство из `sidebar.yml` свойства
3. имя файла

Подраздел

1. `title` из `front-matter` индексного файла markdown/html
2. `title` свойство из `sidebar.yml` свойства
3. имя файла

Обратите внимание, что если пропустить `index` файл в древовидной структуре 
или не указать `title` во вступительной части, ему будет присвоено общее имя `index`. 
То же самое относится к использованию `sidebar.yml`, но не указанию ни `title`, ни `index`, а только подраздела. 
Снова появится общее имя `index`.


### Блог

Функция блога описана [в отдельном документе](blog.md).


### Расширенная конфигурация

#### Полная структура корня сайта

```text
.
└── <site-root>/
    ├── _layouts/
    │   └── ...
    ├── _docs/
    │   └── ...
    ├── _blog/
    │   ├── index.md
    │   └── _posts/
    │       └── ...
    └── _assets/
        ├── js/
        │   └── ...
        ├── img/
        │   └── ...
        └── ...
```

В результате получается статический сайт, содержащий документы, а также блог. 
Он также содержит пользовательские макеты и ассеты. 
Структура визуализируемой документации может быть основана на файловой системе, 
но также может быть переопределена конфигурацией YAML.

#### Структура каталогов сопоставления

Используя файл конфигурации YAML, можно определить, 
как структура исходного каталога должна быть преобразована в структуру выходного каталога.

Взглянем на следующее определение подраздела:

```text
- title: Some other subsection
  index: abc/index.html
  directory: custom-directory
  subsection:
    - page: abc2/page1.md
    - page: foo/page2.md
```

В этом подразделе показана возможность конфигурации YAML отображать структуру каталогов. 
Несмотря на то, что индексная страница и все определенные дочерние элементы находятся в разных каталогах, 
они будут рендериться в `custom-directory`. 
Исходная страница `abc/index.html` будет генерировать страницу `custom-directory/index.html`, 
исходная страница `abc2/page1.md` - `custom-directory/page1.html`, 
а исходная страница `foo/page2.md` - `custom-directory/page2.html`.


---

**Ссылки:**

- [Scaladoc Guide](https://docs.scala-lang.org/scala3/guides/scaladoc/static-site.html)
